
/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2022原作者。
 *
 *根据Apache许可证2.0版（“许可证”）许可；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，否则软件
 *根据许可证分发是在“按原样”的基础上分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证
 *许可证下的限制。
 */

package org.springframework.context;

import java.io.Closeable;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
import org.springframework.core.env.ConfigurableEnvironment;
import org.springframework.core.env.Environment;
import org.springframework.core.io.ProtocolResolver;
import org.springframework.core.metrics.ApplicationStartup;
import org.springframework.lang.Nullable;

/**
 * SPI interface to be implemented by most if not all application contexts.
 * Provides facilities to configure an application context in addition
 * to the application context client methods in the
 * {@link org.springframework.context.ApplicationContext} interface.
 *
 * <p>Configuration and lifecycle methods are encapsulated here to avoid
 * making them obvious to ApplicationContext client code. The present
 * methods should only be used by startup and shutdown code.
 *
 * @author Juergen Hoeller
 * @author Chris Beams
 * @author Sam Brannen
 * @since 03.11.2003
 */
/**
 *SPI接口将由大多数（如果不是所有的话）应用程序上下文实现。
 *提供配置应用程序上下文的工具
 *中的应用程序上下文客户端方法
 *｛@link org.springframework.context.ApplicationContext｝接口。
 *
 *<p>此处封装了配置和生命周期方法，以避免
 *使它们对ApplicationContext客户端代码显而易见。现在
 *方法只能由启动和关闭代码使用。
 *
 *@作者Juergen Hoeller
 *@作者Chris Beams
 *@作者Sam Brannen
 *@自2003年11月3日起
 */
public interface ConfigurableApplicationContext extends ApplicationContext, Lifecycle, Closeable {

	/**
	 * Any number of these characters are considered delimiters between
	 * multiple context config paths in a single String value.
	 * @see org.springframework.context.support.AbstractXmlApplicationContext#setConfigLocation
	 * @see org.springframework.web.context.ContextLoader#CONFIG_LOCATION_PARAM
	 * @see org.springframework.web.servlet.FrameworkServlet#setContextConfigLocation
	 */
	/**
	 *这些字符中的任意数量都被视为介于
	 *单个String值中的多个上下文配置路径。
	 *@请参阅org.springframework.context.support.AbstractXmlApplicationContext#setConfigLocation
	 *请参阅org.springframework.web.context.ContextLoader#CONFIG_LOCATION_PARAM
	 *请参阅org.springframework.web.servlet.FrameworkServlet#setContextConfigLocation
	 */
	String CONFIG_LOCATION_DELIMITERS = ",; \t\n";

	/**
	 * Name of the ConversionService bean in the factory.
	 * If none is supplied, default conversion rules apply.
	 * @since 3.0
	 * @see org.springframework.core.convert.ConversionService
	 */
	/**
	 *工厂中ConversionService bean的名称。
	 *如果未提供，则应用默认转换规则。
	 *@自3.0起
	 *@参见org.springframework.core.covert.ConversionService
	 */
	String CONVERSION_SERVICE_BEAN_NAME = "conversionService";

	/**
	 * Name of the LoadTimeWeaver bean in the factory. If such a bean is supplied,
	 * the context will use a temporary ClassLoader for type matching, in order
	 * to allow the LoadTimeWeaver to process all actual bean classes.
	 * @since 2.5
	 * @see org.springframework.instrument.classloading.LoadTimeWeaver
	 */
	/**
	 *工厂中LoadTimeWeaver bean的名称。如果提供这样的豆，
	 *上下文将使用临时ClassLoader进行类型匹配，按顺序
	 *以允许LoadTimeWeaver处理所有实际的bean类。
	 *@自2.5起
	 *@参见org.springframework.instrument.classloading.LoadTimeWeaver
	 */
	String LOAD_TIME_WEAVER_BEAN_NAME = "loadTimeWeaver";

	/**
	 * Name of the {@link Environment} bean in the factory.
	 * @since 3.1
	 */
	/**
	 *工厂中｛@link Environment｝bean的名称。
	 *@自3.1起
	 */
	String ENVIRONMENT_BEAN_NAME = "environment";

	/**
	 * Name of the System properties bean in the factory.
	 * @see java.lang.System#getProperties()
	 */
	/**
	 *工厂中系统财产bean的名称。
	 *@参见java.lang.System#getProperties（）
	 */
	String SYSTEM_PROPERTIES_BEAN_NAME = "systemProperties";

	/**
	 * Name of the System environment bean in the factory.
	 * @see java.lang.System#getenv()
	 */
	/**
	 *工厂中的系统环境bean的名称。
	 *@参见java.lang.System#getenv（）
	 */
	String SYSTEM_ENVIRONMENT_BEAN_NAME = "systemEnvironment";

	/**
	 * Name of the {@link ApplicationStartup} bean in the factory.
	 * @since 5.3
	 */
	/**
	 *工厂中｛@link ApplicationStartup｝bean的名称。
	 *@自5.3起
	 */
	String APPLICATION_STARTUP_BEAN_NAME = "applicationStartup";

	/**
	 * {@link Thread#getName() Name} of the {@linkplain #registerShutdownHook()
	 * shutdown hook} thread: {@value}.
	 * @since 5.2
	 * @see #registerShutdownHook()
	 */
	/**
	 *｛@linkplain#registerShutdownHook（）的｛@link线程#getName（）名称｝
	 *shutdown hook｝线程：｛@value｝。
	 *@自5.2起
	 *@参见#registerShutdownHook（）
	 */
	String SHUTDOWN_HOOK_THREAD_NAME = "SpringContextShutdownHook";


	/**
	 * Set the unique id of this application context.
	 * @since 3.0
	 */
	/**
	 *设置此应用程序上下文的唯一id。
	 *@自3.0起
	 */
	void setId(String id);

	/**
	 * Set the parent of this application context.
	 * <p>Note that the parent shouldn't be changed: It should only be set outside
	 * a constructor if it isn't available when an object of this class is created,
	 * for example in case of WebApplicationContext setup.
	 * @param parent the parent context
	 * @see org.springframework.web.context.ConfigurableWebApplicationContext
	 */
	/**
	 *设置此应用程序上下文的父级。
	 *<p>请注意，不应更改父级：只应在外部设置
	 *如果构造函数在创建此类的对象时不可用，
	 *例如在WebApplicationContext设置的情况下。
	 *@param parent父上下文
	 *@请参阅org.springframework.web.context.ConfigurableWebApplicationContext
	 */
	void setParent(@Nullable ApplicationContext parent);

	/**
	 * Set the {@code Environment} for this application context.
	 * @param environment the new environment
	 * @since 3.1
	 */
	/**
	 *为此应用程序上下文设置｛@code Environment｝。
	 *@param environment新环境
	 *@自3.1起
	 */
	void setEnvironment(ConfigurableEnvironment environment);

	/**
	 * Return the {@code Environment} for this application context in configurable
	 * form, allowing for further customization.
	 * @since 3.1
	 */
	/**
	 *以可配置的方式返回此应用程序上下文的｛@code Environment｝
	 *形式，允许进一步定制。
	 *@自3.1起
	 */
	@Override
	ConfigurableEnvironment getEnvironment();

	/**
	 * Set the {@link ApplicationStartup} for this application context.
	 * <p>This allows the application context to record metrics
	 * during startup.
	 * @param applicationStartup the new context event factory
	 * @since 5.3
	 */
	/**
	 *为此应用程序上下文设置｛@link ApplicationStartup｝。
	 *<p>这允许应用程序上下文记录度量
	 *在启动过程中。
	 *@param application启动新的上下文事件工厂
	 *@自5.3起
	 */
	void setApplicationStartup(ApplicationStartup applicationStartup);

	/**
	 * Return the {@link ApplicationStartup} for this application context.
	 * @since 5.3
	 */
	/**
	 *返回此应用程序上下文的｛@link ApplicationStartup｝。
	 *@自5.3起
	 */
	ApplicationStartup getApplicationStartup();

	/**
	 * Add a new BeanFactoryPostProcessor that will get applied to the internal
	 * bean factory of this application context on refresh, before any of the
	 * bean definitions get evaluated. To be invoked during context configuration.
	 * @param postProcessor the factory processor to register
	 */
	/**
	 *添加一个新的BeanFactoryPostProcessor，该处理器将应用于内部
	 *刷新时，在任何
	 *对bean定义进行评估。要在上下文配置期间调用。
	 *@param postProcessor要注册的工厂处理器
	 */
	void addBeanFactoryPostProcessor(BeanFactoryPostProcessor postProcessor);

	/**
	 * Add a new ApplicationListener that will be notified on context events
	 * such as context refresh and context shutdown.
	 * <p>Note that any ApplicationListener registered here will be applied
	 * on refresh if the context is not active yet, or on the fly with the
	 * current event multicaster in case of a context that is already active.
	 * @param listener the ApplicationListener to register
	 * @see org.springframework.context.event.ContextRefreshedEvent
	 * @see org.springframework.context.event.ContextClosedEvent
	 */
	/**
	 *添加一个新的ApplicationListener，它将在上下文事件中得到通知
	 *例如上下文刷新和上下文关闭。
	 *<p>请注意，此处注册的任何ApplicationListener都将被应用
	 *在刷新时（如果上下文尚未处于活动状态），或者使用
	 *在上下文已经处于活动状态的情况下，当前事件多播。
	 *@param listener要注册的ApplicationListener
	 *@参见org.springframework.context.event.ContextRefreshedEvent
	 *@参见org.springframework.context.event.ContextClosedEvent
	 */
	void addApplicationListener(ApplicationListener<?> listener);

	/**
	 * Remove the given ApplicationListener from this context's set of listeners,
	 * assuming it got registered via {@link #addApplicationListener} before.
	 * @param listener the ApplicationListener to deregister
	 * @since 6.0
	 */
	/**
	 *从该上下文的侦听器集合中删除给定的ApplicationListener，
	 *假设它之前是通过{@link#addApplicationListener}注册的。
	 *@param listener要注销的ApplicationListener
	 *@自6.0起
	 */
	void removeApplicationListener(ApplicationListener<?> listener);

	/**
	 * Specify the ClassLoader to load class path resources and bean classes with.
	 * <p>This context class loader will be passed to the internal bean factory.
	 * @since 5.2.7
	 * @see org.springframework.core.io.DefaultResourceLoader#DefaultResourceLoader(ClassLoader)
	 * @see org.springframework.beans.factory.config.ConfigurableBeanFactory#setBeanClassLoader
	 */
	/**
	 *指定ClassLoader来加载类路径资源和bean类。
	 *＜p＞这个上下文类加载器将被传递到内部bean工厂。
	 *@自5.2.7起
	 *@参见org.springframework.core.io.DefaultResourceLoader#DefaultResourceLoader（ClassLoader）
	 *请参阅org.springframework.beans.factory.config.ConfiguratableBeanFactory#setBeanClassLoader
	 */
	void setClassLoader(ClassLoader classLoader);

	/**
	 * Register the given protocol resolver with this application context,
	 * allowing for additional resource protocols to be handled.
	 * <p>Any such resolver will be invoked ahead of this context's standard
	 * resolution rules. It may therefore also override any default rules.
	 * @since 4.3
	 */
	/**
	 *使用此应用程序上下文注册给定的协议解析器，
	 *从而允许处理额外的资源协议。
	 *<p>任何这样的解析器都将在该上下文的标准之前调用
	 *决议规则。因此，它也可以覆盖任何默认规则。
	 *@自4.3起
	 */
	void addProtocolResolver(ProtocolResolver resolver);

	/**
	 * Load or refresh the persistent representation of the configuration, which
	 * might be from Java-based configuration, an XML file, a properties file, a
	 * relational database schema, or some other format.
	 * <p>As this is a startup method, it should destroy already created singletons
	 * if it fails, to avoid dangling resources. In other words, after invocation
	 * of this method, either all or no singletons at all should be instantiated.
	 * @throws BeansException if the bean factory could not be initialized
	 * @throws IllegalStateException if already initialized and multiple refresh
	 * attempts are not supported
	 */
	/**
	 *加载或刷新配置的持久表示
	 *可能来自基于Java的配置、XML文件、财产文件、
	 *关系数据库模式或某种其他格式。
	 *<p>由于这是一个启动方法，它应该销毁已经创建的singleton
	 *如果失败，避免资源悬空。换句话说，在调用之后
	 *对于这个方法，要么全部实例化，要么根本不实例化singleton。
	 *如果bean工厂无法初始化，则@throws BeansException
	 *@throws IllegalStateException（如果已初始化并多次刷新）
	 *不支持尝试
	 */
	void refresh() throws BeansException, IllegalStateException;

	/**
	 * Register a shutdown hook with the JVM runtime, closing this context
	 * on JVM shutdown unless it has already been closed at that time.
	 * <p>This method can be called multiple times. Only one shutdown hook
	 * (at max) will be registered for each context instance.
	 * <p>As of Spring Framework 5.2, the {@linkplain Thread#getName() name} of
	 * the shutdown hook thread should be {@link #SHUTDOWN_HOOK_THREAD_NAME}.
	 * @see java.lang.Runtime#addShutdownHook
	 * @see #close()
	 */
	/**
	 *向JVM运行时注册一个关闭挂钩，关闭此上下文
	 *在JVM关闭时，除非它当时已经关闭。
	 *<p>此方法可以调用多次。只有一个停机挂钩
	 *（最大值）将为每个上下文实例注册。
	 *＜p＞从Spring Framework 5.2开始，的｛@linkplain Thread#getName（）name｝
	 *关机挂钩线程应该是{@link#shutdown_hook_thread_NAME}。
	 *@参见java.lang.Runtime#addShutdownHook
	 *@见#close（）
	 */
	void registerShutdownHook();

	/**
	 * Close this application context, releasing all resources and locks that the
	 * implementation might hold. This includes destroying all cached singleton beans.
	 * <p>Note: Does <i>not</i> invoke {@code close} on a parent context;
	 * parent contexts have their own, independent lifecycle.
	 * <p>This method can be called multiple times without side effects: Subsequent
	 * {@code close} calls on an already closed context will be ignored.
	 */
	/**
	 *关闭此应用程序上下文，释放
	 *实施可能会坚持下去。这包括销毁所有缓存的单例bean。
	 *<p>注意：<i>是否</i>在父上下文上调用{@code close}；
	 *父上下文有自己独立的生命周期。
	 *<p>此方法可以多次调用而不会产生副作用：后续
	 *对已关闭的上下文的｛@code close｝调用将被忽略。
	 */
	@Override
	void close();

	/**
	 * Determine whether this application context is active, that is,
	 * whether it has been refreshed at least once and has not been closed yet.
	 * @return whether the context is still active
	 * @see #refresh()
	 * @see #close()
	 * @see #getBeanFactory()
	 */
	/**
	 *确定该应用程序上下文是否处于活动状态，
	 *是否至少刷新过一次并且尚未关闭。
	 *@return上下文是否仍处于活动状态
	 *@见#refresh（）
	 *@见#close（）
	 *@参见#getBeanFactory（）
	 */
	boolean isActive();

	/**
	 * Return the internal bean factory of this application context.
	 * Can be used to access specific functionality of the underlying factory.
	 * <p>Note: Do not use this to post-process the bean factory; singletons
	 * will already have been instantiated before. Use a BeanFactoryPostProcessor
	 * to intercept the BeanFactory setup process before beans get touched.
	 * <p>Generally, this internal factory will only be accessible while the context
	 * is active, that is, in-between {@link #refresh()} and {@link #close()}.
	 * The {@link #isActive()} flag can be used to check whether the context
	 * is in an appropriate state.
	 * @return the underlying bean factory
	 * @throws IllegalStateException if the context does not hold an internal
	 * bean factory (usually if {@link #refresh()} hasn't been called yet or
	 * if {@link #close()} has already been called)
	 * @see #isActive()
	 * @see #refresh()
	 * @see #close()
	 * @see #addBeanFactoryPostProcessor
	 */
	/**
	 *返回此应用程序上下文的内部bean工厂。
	 *可用于访问底层工厂的特定功能。
	 *＜p＞注意：不要使用它来对bean工厂进行后处理；单线态
	 *将在之前已经实例化。使用BeanFactoryPostProcessor
	 *以在接触beans之前拦截BeanFactory设置过程。
	 *<p>通常，只有在上下文
	 *处于活动状态，即介于{@link#refresh（）}和{@link#关闭（）}之间。
	 *｛@link#isActive（）｝标志可用于检查上下文
	 *处于适当的状态。
	 *@返回底层bean工厂
	 *@throws IllegalStateException如果上下文不包含内部
	 *bean工厂（通常如果尚未调用{@link#refresh（）}，或者
	 *如果已经调用了{@link#close（）}）
	 *@参见#isActive（）
	 *@见#refresh（）
	 *@见#close（）
	 *@参见#addBeanFactoryPostProcessor
	 */
	ConfigurableListableBeanFactory getBeanFactory() throws IllegalStateException;

}
